Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

SoundMeter

Inherits From:	View : Responder : Object

Declared In:	soundkit/SoundMeter.h

Class Description

A SoundMeter is a view that displays the amplitude level of a sound as it's being recorded or played back.  There are two working parts to the meter:  A continuously-updated ªrunning barº that lengthens ands shrinks to depict the current amplitude level, and a ªpeak bubbleº that displays and holds the greatest amplitude that was detected within the last few samples.  An optional bezeled border is drawn around the object's frame.  

To use a SoundMeter, you must first associate it with a Sound object, through the setSound: method, and then send the SoundMeter a run: message.  To stop the meter's display, you send the object a stop: message.  Neither run: nor stop: affect the performance of the meter's sound.  

You can retrieve a SoundMeter's running and peak values through the floatValue and peakValue methods.  The values that these methods return are valid only while the SoundMeter is running.  A SoundMeter also keeps track of the minimum and maximum amplitude over the duration of a run; these can be retrieved through minValue and maxValue.  All SoundMeter amplitude levels are normalized to fit between 0.0 (inaudible) and 1.0 (maximum amplitude). 

Instance Variables

id sound;

int currentSample;

float currentValue;

float currentPeak;

float minValue;

float maxValue;

float holdTime;

float backgroundGray;

float foregroundGray;

float peakGray;

struct {
	unsigned int  running:1;
	unsigned int  bezeled:1;
	unsigned int shouldStop:1;

} smFlags;

sound 	The object's Sound.

currentSample 	The Sound sample currently being displayed.

currentValue 	The value of the current sample.

currentPeak 	The current value of the peak bubble.

minValue 	The minimum sample value so far.

maxValue 	The maximum sample value so far.

holdTime 	The hold duration of the peak bubble.

backgroundGray 	The background color.

foregroundGray 	The foreground (average bar) color.

peakGray 	The peak bubble color.

smFlags.running 	True if the object is currently running.

smFlags.bezeled 	True if the object draws a border.

smFlags.shouldStop	True if the object has been sent a stop: message.

Method Types

Initializing a SoundMeter instance
- initFrame:

Graphic attributes	- setBezeled:
- isBezeled
- setBackgroundGray:
- backgroundGray
- setForegroundGray:
- foregroundGray
- setPeakGray:
- peakGray

Metering attributes	- setSound:
- sound
- setFloatValue:
- setHoldTime:
- holdTime

Retrieving meter values	- floatValue
- maxValue
- minValue
- peakValue

Operating the object	- run:
- isRunning
- stop:

Drawing the object	- drawCurrentValue
- drawSelf::

Archiving	- read:
- write:

Instance Methods

backgroundGray

- (float)backgroundGray

Returns the SoundMeter's background color.  The default is dark gray (NX_DKGRAY).

drawCurrentValue

- drawCurrentValue

Draws the SoundMeter's running bar and peak bubble.  You never invoke this method directly; it's invoked automatically while the SoundMeter is running.  You can override this method to change the look of the running bar and peak bubble.  Returns self.

drawSelf::

- drawSelf:(const NXRect *)rects :(int)rectCount

Draws all the components of the SoundMeter (frame, running bar, and peak bubble).  You never invoke this method directly; however, you can override it in a subclass to change the way the components are displayed.  Returns self.

floatValue

- (float)floatValue

Returns the current running amplitude value as a floating-point number between 0.0 and 1.0.  This is the amplitude level that's displayed by the running bar.

foregroundGray

- (float)foregroundGray

Returns the color of the running bar.  The default is light gray (NX_LTGRAY).

holdTime

- (float)holdTime

Returns the SoundMeter's hold timeÐthe amount of time during which a peak amplitude is detected and displayed by the peak bubbleÐin seconds.  The default is 0.7 seconds.

initFrame:

- initFrame:(const NXRect *)frameRect

Initializes the SoundMeter, fitting its graphic components within frameRect.  The object's attributes are initialized as follows:

Attribute	Value

Peak hold time	0.7 seconds
Background gray	NX_DKGRAY
Running bar gray	NX_LTGRAY
Peak bubble gray	NX_WHITE
Border	bezeled

Returns self.

isBezeled

- (BOOL)isBezeled

Returns YES (the default) if the SoundMeter has a border; otherwise, returns NO.  Note that the SoundMeter class doesn't provide a method to change the type of borderÐit can display a bezeled border or none at all.

isRunning

- (BOOL)isRunning

Returns YES if the SoundMeter is currently running; otherwise, returns NO.  The SoundMeter's status doesn't depend on the activity of its Sound object.

maxValue

- (float)maxValue

Returns the maximum running value so far.  You can invoke this method after you stop this SoundMeter to retrieve the overall maximum value for the previous performance.  The maximum value is cleared when you restart the SoundMeter.

minValue

- (float)minValue

Returns the minimum running value so far.  You can invoke this method after you stop this SoundMeter to retrieve the overall minimum value for the previous performance.  The minimum value is cleared when you restart the SoundMeter.

peakGray

- (float)peakGray

Returns the SoundMeter's peak bubble gray.  The default is white (NX_WHITE).

peakValue

- (float)peakValue

Returns the most recently detected peak value as a floating-point number between 0.0 and 1.0.  This is the amplitude level that's displayed by the peak bubble.

read:

- read:(NXTypedStream *)aStream

Unarchives the SoundMeter by reading it from aStream.  Returns self.

run:

- run:sender

Starts the SoundMeter running.  The object SoundMeter must have a Sound object associated with it for this method to have an effect.  Note that this method only affects the state of the SoundMeterÐit doesn't trigger any activity in the Sound.  Returns self.

setBackgroundGray:

- setBackgroundGray:(float)aValue

Sets the SoundMeter's background color.  The default is dark gray (NX_DKGRAY).  Returns self.

setBezeled:

- setBezeled:(BOOL)aFlag

If aFlag is YES, a bezeled border is drawn around the SoundMeter.  If aFlag is NO and the SoundMeter has a frame, the frame is removed.  Returns self.

setFloatValue:

- setFloatValue:(float)aValue

Sets the current running value to aValue.  You never invoke this method directly; it's invoked automatically when the SoundMeter is running.  However, you can reimplement this method in a subclass of SoundMeter.  Returns self.

setForegroundGray:

- setForegroundGray:(float)aValue

Sets the SoundMeter's running bar color.  The default is light gray (NX_LTGRAY).  Returns self.

setHoldTime:

- setHoldTime:(float)seconds

Sets the SoundMeter's peak value hold time in seconds.  This is the amount of time during which peak amplitudes are detected and held by the peak bubble.  Returns self.

setPeakGray:

- setPeakGray:(float)aValue

Sets the SoundMeter's peak bubble color.  The default is white (NX_WHITE).  Returns self.

setSound:

- setSound:aSound

Sets the SoundMeter's Sound object.  Returns self.

sound

- sound

Returns the Sound object that the SoundMeter is metering.

stop:

- stop:sender

Stops the SoundMeter's metering activity.  Note that this method only affects the state of the SoundMeterÐit doesn't trigger any activity in the Sound.  Returns self.

write:

- write:(NXTypedStream *)aStream

Archives the SoundMeter by writing it to aStream.  Returns self.